home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / DCLAP 6d / dclap6d / Docs / Announce next >
Encoding:
Text File  |  1996-07-05  |  31.0 KB  |  668 lines  |  [TEXT/R*ch]
  1. Release 2.8 - 4/12/93
  2.   Original README below is followed by update info at end of this file.
  3. ***************************************************************************
  4. *
  5. *           Release 2.0 of NCBI Software Toolkit Available
  6. *                             10/92
  7. *
  8. ***************************************************************************
  9.  
  10.     This is to announce the availability of release 2.0 of the NCBI
  11. Software Development Kit.  This includes the version of the ASN.1
  12. specification which will be "frozen" for the next 12 months.  No changes
  13. will be made to data produced by NCBI which is incompatible with that
  14. specification for one year.  This means that the software in release 2.0
  15. will be able to read and write NCBI data for one year as well without
  16. change.
  17.  
  18.     We expect to adding functionality to the software tools over the course
  19. of this year, and these additions will be made part of periodic software
  20. releases.  However, if you do not care for the additional functionality
  21. you do not need to change your software.
  22.  
  23.     In six months we will solicit and propose changes in the ASN.1
  24. specification for next year.  In nine months we will freeze the proposals
  25. and produce sample data files and software that conforms to the new spec.
  26. In twelve months we will begin producing data releases that conform to the
  27. new spec.
  28.  
  29.     Of course, in the event of an unforseen, catastrophic bug, we will be
  30. forced to make an emergency release, but we will do everything in our
  31. power to avoid this.  And, there are always new releases of operating systems
  32. and compilers, which may uncover or create new problems, but unfortunately
  33. this sort of thing is beyond our control.  However, it is in our interest
  34. (and yours) to keep this to an absolute minimum, and that is what we will
  35. do.
  36.  
  37.     The release is available for anonymous ftp from ncbi.nlm.nih.gov.
  38. cd toolbox\ncbi_tools
  39. bin
  40. get ncbi.tar.Z
  41. quit
  42.  
  43.     There is also a self-extracting Mac version (ncbi.sea.hqx) and a self-
  44. extracting PC version (ncbiZ.exe) in the same directory.  All three versions
  45. contain source code for ALL supported hardware platforms.
  46.  
  47.     In toolbox\vms_utils are a readme file and source code for a number
  48. of utilities to facilitate transfer of the source code onto VMS systems.
  49.  
  50.     The documentation has not caught up with the software and specification.
  51. However, now that it is frozen, documentation writing has begun.  It will
  52. be announced on BITS when it is complete.
  53.  
  54.     The README file from ncbi.tar.Z follows:
  55. Release 2.8 - Update history at end of this file.
  56.  
  57.                          Introduction
  58.  
  59.     This distribution is release 2.0 of the NCBI core library for building
  60. portable software, and AsnLib, a collection of routines for handling ASN.1
  61. data and developing ASN.1 software applications.  AsnLib and the asntool
  62. application are built using the CoreLib routines.  This software supports
  63. release 1.0 of the Entrez cdrom.
  64.  
  65.  
  66. The lowest layer of code is the CoreLib [chapter 2].  These are multi-
  67. platform functions for memory allocation (including byte stores), string 
  68. manipulation, file input and output, error and general messages, and 
  69. time and date notification.  These functions have been written only 
  70. where we found that the existing ANSI functions were not sufficiently 
  71. multi-platform or well- behaved among all of the platforms that we 
  72. support.  For each platform (a combination of processor, operating 
  73. system, compiler, and windowing system), we supply a specific ncbilcl.h 
  74. file, which contains typedefs and defines for multi-platform symbols, 
  75. and includes a number of standard header files.  (For example, 
  76. ncbilcl.msw is used for the Microsoft C compiler under Microsoft Windows 
  77. on the PC.)  Use of these symbols, and of the functions in the CoreLib, 
  78. allow us to write multi-platform source code for a variety of disparate 
  79. platforms.
  80.  
  81. The next layer of code is the AsnLib stream reader [chapter 5].  This is 
  82. used in conjunction with a header file and a parse table loader file, 
  83. both of which are produced by processing the formal ASN.1 specification 
  84. with the AsnTool application [chapter 4]. The symbolic defines in the 
  85. header file are pointers into the parse table, in which the ASN.1 
  86. specification is represented.  To read at the stream reader level, a 
  87. program alternates between calls to AsnReadId and AsnReadVal.  AsnReadId 
  88. returns a pointer into the parse table, which can be compared against 
  89. the defines in the AsnTool-generated header.  For example, in the 
  90. specification for MEDLINE records, the Medline-entry section has an item 
  91. called "uid", for the unique ID of the record.  This is symbolized in 
  92. the header file as MEDLINE_ENTRY_uid.  When AsnReadId returns this 
  93. symbol, the program calls AsnReadVal to obtain the uid for that record. 
  94. AsnKillValue is also needed to free any memory allocated by AsnReadVal, 
  95. which occurs when the value is a string and not an integer.  The entire 
  96. set of records on the Entrez CD-ROM can be read as a single stream with 
  97. the AsnLib functions.
  98.  
  99. The ASN.1 records may be accessed at a higher level through the object 
  100. loaders [chapter 6], which utilize the stream processing functions to 
  101. load C memory structures with the contents of the ASN.1 objects. For 
  102. each ASN.1 object we specify, we also define an equivalent C memory 
  103. structure.  The object loader level of code contains functions to read 
  104. and write each ASN.1 object.  These are hierarchical, as are the ASN.1 
  105. specifications.  Calling the top level loader, SeqEntryAsnRead, will 
  106. load an entire SeqEntry from an open AsnIo channel, and will return a 
  107. pointer to the loaded memory structure.  The read function for an AsnIo 
  108. channel can be swapped to refer to a normal disk file, a network socket, 
  109. or to compressed data, which it automatically decompresses.  The object 
  110. loader code can interconvert between the highly-branched memory object 
  111. and a linear ASN.1 message with complete fidelity.  The object loaders 
  112. have additional functions, including the ability to explore the 
  113. structure and notify the program when particular data elements are 
  114. encountered.  The entire contents of the Entrez CD-ROM can also be 
  115. streamed through the object loaders.  However, most calls to the object 
  116. loaders for simply reading a particular record are done via the data 
  117. access functions (see below).
  118.  
  119. The data access functions allow a program to call the object loaders on 
  120. a sequence or MEDLINE record given the uid of the record [chapter 7].  
  121. This will get the data into memory regardless of whether the data are 
  122. compressed on the Entrez CD-ROM or are obtained through a service over 
  123. the Internet. This means that a detailed understanding of the files and 
  124. formats on the Entrez disc is not needed by application programmers. The 
  125. function to load a sequence record, SeqEntryGet, needs the uid to 
  126. retrieve and a complexity code parameter. A sequence record is in the 
  127. form of a NucProt set.  This contains a nucleotide (which may itself be 
  128. composed of segments) and all of the proteins it is known to encode.  
  129. The set of segments is called a SegSet, and the individual sequences are 
  130. called BioSeqs.  We have taken the liberty of producing this integrated 
  131. view, but the complexity code parameter allows the record to be easily 
  132. loaded in a simpler, more traditional form, if desired.  The accession 
  133. number term list is built to supply the proper uids to support this 
  134. facility.  This access library is compatible with Entrez release 1.0 or
  135. later only.
  136.  
  137. The sequence utilities and application programmer interface layer 
  138. [chapter 7] allows exploration of the loaded memory structures and 
  139. generation of standard literature or sequence reports from those 
  140. objects.  For example, a BioSeq can be converted to FASTA or GenBank 
  141. flat file formats and saved to a file, and a MEDLINE record can be saved 
  142. in MEDLARS format, which is suitable for entry into personal 
  143. bibliographic database programs.  A sequence port can be opened that 
  144. gives a simple, linear view of a segmented sequence, converting 
  145. alphabets, merging exon segments, and dealing with information on both 
  146. strands of the DNA.  This layer also includes some functions to explore 
  147. the NucProt set.  The explore functions visit each individual BioSeq in 
  148. the set, calling a callback function for each sequence node so that a 
  149. program can examine feature tables and other information that are 
  150. associated with the NucProt or SegSets or with the individual sequences.
  151.  
  152. Vibrant is a multi-platform user interface development library that runs 
  153. on the Macintosh, Microsoft Windows on the PC, or X11 and OSF/Motif on 
  154. UNIX and VAX computers [separate documentation].  It is used to build 
  155. the graphical interface for the Entrez application (whose source code is 
  156. in the browser directory). The philosophy behind Vibrant is that 
  157. everything in the published user interface guidelines (the generic 
  158. behavior of windows, menus, buttons, etc.), as well as positioning and 
  159. sizing of graphical control objects, is taken care of automatically.  
  160. The program provides callback functions that are notified when the user 
  161. has manipulated an object. Vibrant and Entrez code are not supported, 
  162. but are provided on an as-is basis.
  163.  
  164. The advantage of using AsnLib and the object loaders, as they are 
  165. implemented, is that application program developers merely need to 
  166. recompile their programs with the new (AsnTool-generated) header files 
  167. and load the new parse tables (included with the Entrez software) in 
  168. order to be able to read the new data.  This process is straightforward, 
  169. and will not break existing program code.  The application is free to 
  170. ignore new fields if it does not choose to take advantage of the new 
  171. kinds of information.
  172.  
  173. The documentation is currently being brought up to date.  The programs 
  174. in the demo directory are designed to teach the proper use of many of 
  175. the functions discussed above.  Many of these programs are not yet 
  176. documented.  The simplest is testcore.c, which tests various functions 
  177. in the CoreLib.  The most complex is getfeat.c, which takes an accession 
  178. number of locus name, determines the unique seq ID, retrieves the entry 
  179. from the Entrez CD-ROM using the data access library, locates all coding 
  180. region features using the explore functions, and prints the DNA 
  181. sequences of all exons using sequence port functions.  If you cannot 
  182. extract and print the doc.tar.Z file, please send an email message with 
  183. your land mailing address and phone number to toolbox@ncbi.nlm.nih.gov, 
  184. and we will mail a copy to you.
  185.  
  186. The contents of the ncbi directory (the highest level, containing the 
  187. NCBI Software Development Kit source code in several subdirectories) is 
  188. shown below.  The readme file contains instructions on copying the 
  189. appropriate make files to be built in the build directory.  The makeall 
  190. file copies headers to the include directory builds four libraries 
  191. (ncbi, ncbiobj, ncbicdr and vibrant), copying them to the lib directory.  
  192. The makedemo file builds the demo programs and the Entrez application:
  193.  
  194.   api           Application Programmer Interface, Sequence Utilities
  195.   asn           ASN.1 specifications for publications and sequences
  196.   asnlib        Source code for AsnLib and asntool
  197.   asnload       AsnLib headers and dynamic parse tables (Mac and PC)
  198.   asnstat       AsnLib headers that use static memory (UNIX and VMS)
  199.   bin           Asntool executable copied here
  200.   browser       Source code for Entrez application
  201.   build         Empty directory for building tools and libraries
  202.   cdromlib      Access routines for data on the Entrez CD-ROM
  203.   config        Configuration files for NCBI software:
  204.     dos
  205.     mac
  206.     unix
  207.     vms
  208.     win
  209.   corelib       Source code for NCBI Core Software Library
  210.   data          Data files used for sequence conversion
  211.   demo          AsnLib and sequence utility demonstration programs
  212.   doc           Documentation in ASCII files
  213.   include       Include files required by applications are copied here
  214.   lib           Libraries copied here
  215.   link          Contains three subdirectories with build accessory files:
  216.     macmpw        Macintosh MPW C
  217.     msdos         Microsoft C and Borland C for DOS
  218.     mswin         Microsoft C and Borland C for Windows
  219.   make          Make files for various systems
  220.   network       Network version of data access (to be added later)
  221.     apple
  222.     entrcli
  223.     entrserv
  224.     ncsasock
  225.     netmanag
  226.     nsclilib
  227.     nsconfig
  228.     nsdaemon
  229.     nsdemocl
  230.   object        Functions for reading and writing complex objects
  231.   readme        File that contains important building instructions
  232.   vibrant       Source code for Vibrant portable interface package
  233.  
  234. The platforms that are supported (as indicated by the suffix on the 
  235. relevant ncbilcl.h file) are shown below.  Those marked with an asterisk 
  236. (*) are available as-is:
  237.  
  238.   370*          IBM 370
  239.   acc           SUN acc compiler
  240.   alf           DEC Alpha under OSF/1
  241.   aov           DEC Alpha under AXP/OpenVMS
  242.   aux*          Macintosh A/UX
  243.   bor           Borland for DOS
  244.   bwn           Borland for Microsoft Windows
  245.   ccr           CenterLine CodeCenter
  246.   cpp           SUN C++
  247.   cra*          Cray
  248.   cvx*          Convex
  249.   gcc           Gnu gcc
  250.   hp *          Hewlett Packard
  251.   mpw           Macintosh Programmer's Workshop
  252.   msc           Microsoft C for DOS
  253.   msw           Microsoft for Windows
  254.   nxt*          NeXT
  255.   r6k*          IBM RS 6000
  256.   sgi           Silicon Graphics
  257.   thc           THINK C on Macintosh
  258.   ult           DEC ULTRIX
  259.   vms           DEC VAX/VMS
  260.  
  261. Questions or comments can be directed to toolbox@ncbi.nlm.nih.gov.
  262.  
  263. It is our intent that the ASN.1 specifications [chapter 3] will be 
  264. frozen for at least 12 months (through September of 1993).  As molecular 
  265. biology progresses, new features (e.g., RNA editing) will need to be 
  266. represented in the ASN.1 specifications.  Proposed additions will be 
  267. made available for evaluation (with code and sample records included) in 
  268. April of 1993, and the specifications will be finalized in July of 1993.  
  269. Changes will be made with every effort given to backward compatibility 
  270. with data.  We expect to add only new choices and optional fields.  
  271. Existing records will thus continue to be valid instances of the new 
  272. specification, eliminating the need for us to reprocess the databases.
  273.  
  274.     While we feel confident we can to hold to this schedule, we hope users
  275. will understand if events force us to make an interim release of some sort.
  276. In addition, we will make releases of software with additional features over
  277. the next year, but the use of such releases will be at the option of the
  278. software developer.
  279.  
  280. ANSI C:
  281.  
  282.     This software requires an ANSI C compiler.  This will be no problem at
  283. all except to people on Sun machines, where the bundled C compiler, cc, is
  284. non-ansi.  However, you can use the Sun unbundled compiler, acc, or the Gnu
  285. compiler, gcc (which is free) and that works just fine.  If you have written
  286. applications on the Sun with non-ANSI functions, the ANSI compilers will
  287. complain.  See the notes below if this is a problem.
  288.  
  289.  
  290.                          Installation
  291. ALL -
  292.      change to the build subdirectory
  293.  
  294. MS-DOS
  295.     (Also see NEW MAKEFILES, below)
  296.      Microsoft C version 7.00
  297.           copy ..\make\*.dos
  298.           ren makeall.dos makefile
  299.           nmake MSC=1       [note: nmake requires windows or DPMI]
  300.           copy ..\config\ncbi.dos ncbi.cfg  
  301.           check paths in ncbi.cfg file
  302.              [see section on CONFIGURATION]
  303.           Optional:
  304.              edit AUTOEXEC.BAT with "set NCBI=[path to directory containing
  305.                     ncbi.cfg".
  306.              reboot to activate
  307.           To make demo programs:
  308.              nmake -f makedemo.dos MSC=1
  309.      Microsoft Windows version 7.00
  310.           copy ..\make\*.dos
  311.           ren makeall.dos makefile
  312.           nmake MSW=1      [note: nmake requires windows or DPMI]
  313.           check paths in "ncbi.ini" as above
  314.           copy ncbi.ini to your windows directory
  315.           To make demos:
  316.              nmake -f makedemo.dos MSW=1
  317.      Borland C++ 3.1
  318.         copy ..\make\*.dos
  319.         ren makeall.dos makefile
  320.         make -DBOR
  321.         then set paths as in Microsoft C, above.
  322.         To make demos:
  323.            make -f makedemo.dos -DBOR
  324.      Borland C++ 3.1 for Windows
  325.         copy ..\make\*.dos
  326.         ren makeall.dos makefile
  327.         make -DBWN
  328.         then set paths as in Microsoft Windows, above.
  329.         To make demos:
  330.             make -f makedemo.dos -DBWN
  331.  
  332. Mac
  333.      tested on THINK C 5.0.4 and MPW C 3.2
  334.      Both - copy config:mac:ncbi.cnf to your System Folder, or to the
  335.                  System Folder:Preferences subfolder
  336.                  edit the "ASNLOAD" line in "ncbi.cnf" to point to the
  337.                    ncbi:asnload directory in this release
  338.                  edit the "DATA" line to point to the ncbi/data directory
  339.      Think C - rename corelib:ncbimain.mac ncbimain.c
  340.                rename corelib:ncbienv.mac ncbienv.c
  341.                rename corelib:ncbilcl.thc ncbilcl.h
  342.                build separate projects, allocating .c files as described
  343.                in the makeall.thc document.
  344.      MPW C -   copy make:makeall.mpw build:makeall.make
  345.                copy make:makedemo.mpw build:makedemo.make
  346.                set directory to build
  347.                build makeall
  348.                build makedemo
  349.  
  350. Unix
  351.      tested on Sun Sparc, Silicon Graphics, IBM 3090 with AIX
  352.      Sun (with gcc version 2.2 but not Vibrant)
  353.           cp ../make/*.unx .
  354.           mv makeall.unx makefile
  355.           make LCL=gcc CC=gcc RAN=ranlib
  356.           To make demos:
  357.              make -f makedemo.unx CC=gcc
  358.      Sun (with gcc version 2.2 with Vibrant)
  359.           cp ../make/*.unx .
  360.           mv makeall.unx makefile
  361.           source ../make/viball.gcc
  362.           To make demos:
  363.              source ../make/vibdemo.gcc
  364.      Silicon Graphics (no Vibrant)
  365.           cp ../make/*.unx .
  366.           mv makeall.unx makefile
  367.           [ edit makefile to delete make $(LIB4) ]
  368.           make LCL=sgi OTHERLIBS="-lm -lPW -lsun"
  369.           To make demos:
  370.             make -f makedemo.unx LCL=sgi OTHERLIBS="-lm -lPW -lsun"
  371.      Silicon Graphics (with Vibrant)
  372.           cp ../make/*.unx .
  373.           mv makeall.unx makefile
  374.           source ../make/viball.sgi
  375.           To make demos:
  376.             source ../make/vibdemo.sgi
  377.  
  378.     Other UNIX: AIX, ULTRIX, NeXt, Sun acc, DEC Alpha OSF/1
  379.           Follows models above.  Read header in makeall.unx and makedemo.unx
  380.     for details.  Look at viball.* and vibdemo.* for model shell scripts for
  381.     Vibrant versions.
  382.  
  383.     for all UNIX, edit .ncbirc as described above for MSC.
  384.     optional edit .login to "setenv NCBI=[path to .ncbirc file"
  385.  
  386. VMS (without Vibrant) on VAX
  387.      $set def [ncbi.build]
  388.      $copy [-.make]*.dcl *.com
  389.      $@makeall
  390.  
  391.      check ncbi.cfg as described above for MSC.
  392.      edit LOGIN.COM to "define NCBI [path to ncbi.cfg file]"
  393.  
  394.     To make demos:
  395.         $@makedemo
  396.  
  397. VMS (with Vibrant) on VAX
  398.      $set def [ncbi.build]
  399.      $copy [-.make]*.dcl *.com
  400.      $@viball
  401.  
  402.      check ncbi.cfg as described above for MSC.
  403.      edit LOGIN.COM to "define NCBI [path to ncbi.cfg file]"
  404.  
  405.     To make demos:
  406.         $@vibdemo
  407.  
  408.                             Testing
  409.  
  410. VMS only:  look in rundemo.dcl in [make] to see how to give command
  411.     line arguments.  Not all demo programs are shown. Run at least testcore.
  412.  
  413. All else:
  414.  
  415.     In build should be a program called testcore.  Type "testcore -" and
  416. it should show you some default arguments.  Type "testcore" and it will
  417. run through a variety of functions in CoreLib, prompting you for responses
  418. along the way.  It should run without a crash or error report.  If you made
  419. Vibrant versions all demos will have startup dialog boxes.  If not, they
  420. take command line arguments.
  421.  
  422.     If testcore runs, read the documentation for CoreLib and for AsnLib. 
  423. In the AsnLib documentation are instructions for running asntool itself.
  424. for running a few of the demo programs.  There are a large number of demo
  425. programs now (including Entrez itself, if you made the Vibrant versions).
  426.  
  427.  
  428.  
  429. CONFIGURATION OR SETTINGS FILES:
  430.  
  431.     One of the fundamental problems in writing portable software concerns
  432. configuration issues.  Each individual user's computer will have its own
  433. particular hardware and software environment, and each machine will have
  434. its disk file  hierarchy set up in a unique manner.  A program that needs 
  435. accessory information, such as help files, parse tables, or  format
  436. converters, must be given a means of finding the data regardless of where
  437. the user has placed the files.  The difficulty is compounded by the different
  438. conventions for naming files and specifying paths on each class of machine.  
  439. For example, the name of a CD-ROM on the Macintosh is fixed, determined by
  440. information on the CD itself, whereas on the PC it is addressed by a drive
  441. letter, which can be assigned by the user, but which cannot be reconciled
  442. with the name the Macintosh sees.
  443.  
  444.     An associated problem is that many programs will want to allow the user
  445. to make persistent changes to parameters.  These parameters typically involve
  446. numbers or font specifications, but may also include paths to data files.  
  447. Some platforms supply such configuration information in preferences files,
  448. others in environment variables.  Manipulating these settings is platform
  449. dependent, as is the format in which the preference is specified.
  450.  
  451.     The NCBI Software Toolkit core library addresses these problems by
  452. providing configuration or settings files.  These are modeled after the .INI
  453. files used by Microsoft Windows.  Settings files are plain ASCII text files
  454. that may be edited by the user or modified by the program.  They are divided 
  455. into sections, each of which is headed by the section name enclosed in square
  456. brackets.  Below each section heading is a series of key=value strings, somewhat
  457. analogous to the environment variables that are used on many platforms.
  458.  
  459.     The ncbi configuration file supplies general purpose configuration
  460. information on paths for commonly used data files.  The typical file set up for
  461. the Entrez application running on the PC under Microsoft Windows is shown below:
  462.  
  463. [NCBI]
  464. ROOT=D:
  465. ASNLOAD=C:\ENTREZ\ASNLOAD\
  466. DATA=C:\ENTREZ\DATA
  467.  
  468.     The only section is entitled NCBI.  The ROOT entry refers to the path to
  469. the Entrez CD-ROM.  In this example, the user has configured the machine to
  470. use drive letter D.  (On the Macintosh, the name of the disc is SEQDATA, which
  471. cannot be changed by the user.)  The ASNLOAD specifies the path to the ASN.1
  472. parse tables.  These files are required by the AsnLib functions, and all
  473. higher-level procedures that call them,  including the Object Loader, Sequence
  474. Utility, and Data Access functions.  Files pointed to by the DATA entry contain 
  475. information necessary to convert biomolecule sequence data into different
  476. alphabets (e.g., unpacking the 2-bit nucleotide code stored on the Entrez CD
  477. into standard IUPAC letters).
  478.  
  479.     Although the contents of a configuration file is similar regardless of
  480. platform, the name of the file and its location is platform dependent.  If the
  481. base name of the configuration file is xxx, then the actual file name is shown
  482. below for each platform:
  483.  
  484. Macintosh                   xxx.cnf
  485. Microsoft Windows           xxx.INI
  486. MS-DOS (without Windows)    xxx.CFG
  487. UNIX                        .xxxrc
  488. VMS                         xxx.cfg
  489.  
  490.     Samples of such files are in subdirectories of \config.  The UNIX version
  491. does not have the leading '.' in filename so you can see it.  Since VMS and
  492. DOS both use the same file name (ncbi.cfg) the DOS version was called ncbi.dos.
  493. You will have to rename it.  Remember these are just models.  You will have to
  494. set the paths appropriately for your machine yourself.
  495.  
  496.     The location in which these files must reside is also platform dependent,
  497. and the functions that manipulate the contents may look in several places to
  498. find these files.
  499.  
  500.     On the Macintosh, the function first looks in the System Folder, then in the
  501. Preferences folder within the System Folder.  Under Microsoft Windows, the file
  502. must be in the Windows directory, along with all of the other .INI files.  Under
  503. DOS without Windows, the function first looks in the current working directory,
  504. then in the directory whose path is specified in the NCBI environment variable.
  505. Under UNIX and VMS, the current working directory is first checked, then the
  506. user's home directory, and finally the directory specified by the NCBI environment
  507. variable.  (Under UNIX, when it uses the environment variable, it will check for
  508. configuration files first without and then with the initial dot.)  On the multi-
  509. user platforms (UNIX and VMS), the use of the NCBI environment variable allows a
  510. common settings file to be used  as the default by multiple users.  If such a
  511. settings file is  changed under program control, it is copied over into the user's
  512. home directory, and the new copy is modified.  The  order of searching for settings
  513. files ensures that this new copy is used in all subsequent operations.
  514.  
  515.  
  516. contents of ASNLOAD are in ncbi/asnload
  517. contents of DATA are in ncbi/data
  518.  
  519. MAJOR CHANGES FROM DOCUMENTATION:
  520.  
  521.     AsnNode structures have proved to be generally useful and moved from AsnLib
  522. to ncbimisc.  In addition, some elements of structs used in the object loaders
  523. were called "class" to match the ASN.1 names.  Class is a C++ reserved word,
  524. so all instances of "class" have been changed to "_class".
  525.  
  526.     To conform to our naming conventions, we have changed the names appropriately:
  527.  
  528. AsnValue = DataVal
  529. AsnNode = ValNode
  530. class = _class
  531.  
  532.     A global search and replace of your code with these strings (not restricted
  533. to words... we want to change AsnNodePtr = ValNodePtr as well) should fix
  534. any problems.  Field names within structures have not been changed.  If your
  535. code uses only the object loaders, you may not find these strings in your
  536. code at all.
  537.  
  538. DATA ACCESS LIBRARIES
  539.  
  540.     cdromlib contains data access routines compatible with release 1.0-6.0
  541. of the Entrez CDROM.  The documentation for these functions are out of
  542. date.  The routines in cdromlib have been split into entrez, sequence, and
  543. medline access functions.  The interface you should normally program to is
  544. defined in accentr.[ch], accseq.[ch], and accml.[ch].  The form of this
  545. calls has been changed to make them compatible with the NCBI network server,
  546. a client/server version of data access.  A program written to use these
  547. calls can access the the cdrom data, the network data, a combination, or
  548. that plus a local database by just fiddling with defines.  The form of the
  549. api for these functions has also been changed to hide the details of storage
  550. and caching more so that the different optimizations done to support cdrom
  551. and network access are transparent to the application programmer.  The end
  552. user tool called "Entrez" now uses these libraries as it's only means of
  553. data access (i.e., you can write an application of your own with any or all
  554. of Entrez's functionality using just these routines).
  555.  
  556. DOCUMENTATION
  557.  
  558.     We are rewriting the documentation to conform with all the new features
  559. contained in this software.  We will add it to the package as soon as possible.
  560.  
  561. DEMO PROGRAMS
  562.  
  563.     As in the tools, there are a number of undocumented programs in the demo
  564. directory as well, that use a number of the utility functions in api.  There
  565. is also a demo program called "getseq" in the cdromlib directory which
  566. retrieves a sequence from the cdrom given any valid sequence id.  These will
  567. be described in more detail in the next set of documentation. Briefly:
  568.  
  569. asn2gnbk.c      converts ASN.1 to GenBank flatfile
  570. asn2rpt.c       converts ASN.1 to human readable report
  571. dosimple.c      converts ASN.1 to a "simple sequence"
  572. getseq.c        gets sequence from Entrez Cdrom using data access library,
  573.                 writes to disk
  574. getfeat.c       ditto, but writes sequence of any CdRegion features to
  575.                  "test.out"
  576. getmesh.c       documented
  577. getpub.c        documented
  578. indexpub.c      documented
  579. seqtest.c       reads ASN.1 sequence, converts to iupac, reports segmented
  580.                 sequences, outputs fasta format to seqtest.out
  581. testcore.c      documented
  582. testobj.c       tests Medline object loader, demonstrates error checking using
  583.                 NULL asnio stream.
  584. entrez          If Vibrant is installed, the full Entrez program is made.
  585. asndhuff        Demonstrates streaming ASN.1 data from the huffman compressed
  586.                 Entrez CDROM (only works on release 1.0 or later).
  587.  
  588.  
  589.  
  590. Update History of this release from 2.0
  591.  
  592. Release 2.8 - 4/12/93
  593.     many small fixes and improvements
  594.     performance improvements in cdromlib
  595.     vibrant improvements
  596.     improvements to toreport and togenbk
  597.  
  598. Release 2.7 - 3/12/93
  599.     continued refinement of access functions
  600.         accentr made "stand-alone" with no dependency on accml, accseq
  601.         See changes in demo program, getseq.c
  602.     minor bug fixes in object loaders
  603.     refinements in tognbk
  604.     many improvements and refinements to vibrant
  605.     bug fix to asnlex.c for piping text asn1 streams
  606.     changed SeqFeat.except to SeqFeat._except to avoid reserved word in
  607.        Win32
  608.  
  609. Release 2.6 - 2-16-93
  610.     much internal rearrangement of access functions at low levels to
  611.         accommodate 2 cdrom, and network data access. Invisible to
  612.         applications
  613.     access.doc - a brief writeup on data access and exploring in /doc
  614.     improvements to toreport and tognbk for more sequence data sources
  615. Release 2.5 - 1-4-93
  616.     many small fixes and improvements
  617.     asnlib: added generic copy (through file) AsnIoCopy(), copy (in memory)
  618.         AsnIoMemCopy(), and compare in memory, AsnIoMemComp() for any object
  619.         define in object/*.h
  620.     vms version: (Will Gilbert)
  621.         a new Makefile which compiles the sources from there native directory
  622.         This version also checks to see if the user's system has the proper
  623.          include file to make the vibrant library.
  624.         Support for OpenVMS on DEC Alpha machine added.
  625.     data access libraries:
  626.         Changed data access library so that CD-only, network only, or Net+Cd
  627.           may be built from the same baseline.
  628.         Eliminated memory leaks in data access library.
  629.     environment:
  630.         Modified ncbienv.* so that GetAppParam() holds the last-read configuration
  631.           file in a cache. Also modified GetAppParam() and SetAppParam() so that
  632.           they can read all the keys in a section, or destroy a section, if the
  633.           key parameter is NULL.
  634.     files:
  635.         Modified ncbifile.c so that EjectCd() takes the raw device name as an
  636.           extra parameter.
  637.     configuration files:
  638.         Added VMS ncbi config files for the various multi-CD/hard disk configurations,
  639.           and moved all ncbi and entrez config files into their appropriate config
  640.           subdirectories (vms, unix, win, etc.).
  641.     demo programs:
  642.         Will Gilbert added many tutorial comments to getseq.c, getfeat.c, and
  643.           seqtest.c
  644.  
  645. Release 2.4 - 12-3-92
  646.     sequtil.c - improvements to BioseqContextGetSeqFeat() and SeqIdPrint().
  647.     toreport.c - improvements for PDB data
  648.     togenbnk?.c - improvements for unusual ASN.1
  649.     objloc.c  - bug fix in reading release date for PDB id.
  650.     seqport.c - addition of translation routine given CdRegion
  651.  
  652.     data access libraries -
  653.       support for pre-release 0.6 removed
  654.       support for multiple CDROM's (Entrez:Sequences and Entrez:MEDLINE) at
  655.          once.
  656.     vibrant - performance improvements
  657.  
  658. Release 2.3 - 
  659.     ncbimain.xxx - GetArgs now handles negative numbers correctly
  660.  
  661. Release 2.2 - 10-29-92
  662.     objfeat.c - write to uninitialized memory when reading a tRNA feature
  663.                 which contains codon, but no amino acid transferred.
  664.  
  665. Release 2.1 - 10/22/92
  666.     ncbifile.c - VMS open did not work correctly on CDROM.
  667.     objseq.c   - Seq-hist incorrectly read
  668.